Personal Computer World 2009 February/PCWFEB09.iso/Software/Linux/SLAX 6.0.8/slax-6.0.8.iso/slax/base/006-devel.lzm/usr/include/usbpp.h

C/C++ Source or Header | 2007-02-16 | 23.9 KB | 856 lines

// -*- C++;indent-tabs-mode: t; tab-width: 4; c-basic-offset: 4; -*-
#ifndef __USBPP_HEADER__
#define __USBPP_HEADER__

#include <string>
#include <list>

#include <usb.h>

/*
 * The following usb.h function is not wrapped yet:
 *  char *usb_strerror(void);
 */


/**
 * \brief Classes to access Universal Serial Bus devices
 *
 * The USB Namespace provides a number of classes to work
 * with Universal Serial Bus (USB) devices attached to the
 * system.
 *
 * \author Brad Hards
 */
namespace USB {

    class Device;

    /**
     * \brief Class representing a device endpoint
     *
     * This class represents a device endpoint. You need this class to
     * perform bulk reads and writes.
     *
     */
    class Endpoint {
        /**
         * Busses is a friend because it fills in the descriptor type
         * information on initialisation and rescan.
         */
        friend class Busses;
    public:
        Endpoint() {};

#ifdef USE_UNTESTED_LIBUSBPP_METHODS
        /**
         * \brief Bulk write
         *
         * This method performs a bulk transfer to the endpoint.
         *
         * \param message is the message to be sent.
         * \param timeout is the USB transaction timeout in milliseconds
         *
         * \returns the number of bytes sent, or a negative value on
         * failure
         */
        int bulkWrite(QByteArray message, int timeout = 100);

        /**
         * \brief Bulk read
         *
         * This method performs a bulk transfer from the endpoint.
         *
         * \param length is the maximum data transfer required.
         * \param message is the message that was received.
         * \param timeout is the USB transaction timeout in milliseconds
         *
         * \returns the number of bytes received, or a negative value on
         * failure
         */
        int bulkRead(int length, unsigned char *message, int timeout = 100);

        /**
         * \brief Reset endpoint
         *
         * This method resets the endpoint.
         */
        int reset(void);

        /**
         * \brief Clear halt
         *
         * This method clears a halt (stall) on the endpoint.
         */
        int clearHalt(void);

#endif /* USE_UNTESTED_LIBUSBPP_METHODS */

        /**
         * \brief Endpoint descriptor information output
         *
         * This method dumps out the various characteristics
         * of the endpoint to standard output.
         *
         * It is mostly useful for debugging.
         */
        void dumpDescriptor(void);

    private:
        void setDescriptor(struct usb_endpoint_descriptor);
        void setParent(Device *parent);
        u_int8_t  m_Length;
        u_int8_t  m_DescriptorType;
        u_int8_t  m_EndpointAddress;
        u_int8_t  m_Attributes;
        u_int16_t m_MaxPacketSize;
        u_int8_t  m_Interval;
        u_int8_t  m_Refresh;
        u_int8_t  m_SynchAddress;
        Device    *m_parent;
    };

    class AltSetting : public std::list<Endpoint *> {
        /**
         * Busses is a friend because it fills in the descriptor type
         * information on initialisation and rescan.
         */
        friend class Busses;
    public:
        AltSetting() {};
        u_int8_t numEndpoints(void);

        /**
         * \brief AltSetting descriptor information output
         *
         * This method dumps out the various characteristics
         * of the alternate setting to standard output.
         *
         * It is mostly useful for debugging.
         */
        void dumpDescriptor(void);

        Endpoint *firstEndpoint(void);
        Endpoint *nextEndpoint(void);
        Endpoint *lastEndpoint(void);

    private:
        std::list<Endpoint *>::const_iterator iter;

        void setDescriptor(struct usb_interface_descriptor);
        /* we don't use a normal usb_interface_descriptor */
        /* because that would bring in the endpoint list */
        u_int8_t m_Length;
        u_int8_t m_DescriptorType;
        u_int8_t m_InterfaceNumber;
        u_int8_t m_AlternateSetting;
        u_int8_t m_NumEndpoints;
        u_int8_t m_InterfaceClass;
        u_int8_t m_InterfaceSubClass;
        u_int8_t m_InterfaceProtocol;
        u_int8_t m_Interface;
    };

    /**
     * \brief Class representing an interface of a Device
     *
     * The Interface class represents a USB interface
     * for a device attached to a Universal Serial Bus.
     *
     * Interfaces are the main element of the USB class
     * structure.
     *
     * \author Brad Hards
     */
    class Interface : public std::list<AltSetting *> {
        /**
         * Busses is a friend because it fills in the descriptor type
         * information on initialisation and rescan.
         */
        friend class Busses;
    public:
        Interface() {};

#ifdef LIBUSB_HAS_GET_DRIVER_NP
        /**
         * \brief get the current driver for an interface
         *
         * \param driver a string containing the name of the current
         * driver for the interface. You can typically pass in an empty
         * string for this.
         *
         * \return length of string, or 0 on error.
         */
        int driverName(std::string &driver);
#endif

#ifdef USE_UNTESTED_LIBUSBPP_METHODS
        /**
         * \brief Claim this interface
         *
         * This method claims the interface. You have to claim the
         * interface before performing any operations on the interface (or
         * on endpoints that are part of the interface).
         *
         * \return 0 on success or negative number on error.
         */
        int claim(void);

        /**
         * \brief Release this interface
         *
         * This method releases the interface. You should release the
         * interface after all operations on it (and any lower level
         * endpoints) are completed.
         *
         * \return 0 on success or negative number on error.
         */
        int release(void);

        /**
         * \brief Set interface alternate setting
         *
         * This method sets the interface to a particular AltSetting.
         *
         * \param altSettingNumber the AltSetting that the interface
         * should be changed to.
         *
         * \return 0 on success, or a negative number in case of error.
         */
        int setAltSetting(int altSettingNumber);
#endif /* USE_UNTESTED_LIBUSBPP_METHODS */

        /**
         * \brief Number of Alternative Settings that this interface has
         *
         * This is a simple accessor method that specifies the number
         * alternative settings that this device interface has.
         */
        u_int8_t numAltSettings(void);

        /**
         * \brief First AltSetting for the Interface
         *
         * This method returns a pointer to the first AltSetting
         * for the Interface.
         *
         * See nextAltSetting() for an example of how it might be
         * used.
         *
         * \see nextAltSetting(), lastAltSetting(), numAltSettings()
         */
        AltSetting *firstAltSetting(void);

        /**
         * \brief Next AltSetting for the Interface
         *
         * This method returns a pointer to the next AltSetting
         * for the Interface.
         *
         * If you want to iterate through each AltSetting on
         * a device, you can use something like the following:
         * \code
         * USB::Configuration *this_Configuration;
         * this_Configuration = device->firstConfiguration();
         * for (i=0; i < device->numConfigurations(); i++) {
         *     this_Configuration->dumpDescriptor();
         *   USB::Interface *this_Interface;
         *   this_Interface = this_Configuration->firstInterface();
         *   for (j=0; j < this_Configuration->numInterfaces(); j++) {
         *     USB::AltSetting *this_AltSetting;
         *     this_AltSetting = this_Interface->firstAltSetting();
         *     for (k=0; k < this_Interface->numAltSettings(); k++) {
         *       // do something with this_AltSetting
         *       this_AltSetting = this_Interface->nextAltSetting();
         *     }
         *   this_Interface = this_Configuration->nextInterface();
         *   }
         *   this_Configuration = device->nextConfiguration();
         * }
         * \endcode
         *
         * \see firstAltSetting(), lastAltSetting(), numAltSettings()
         */
        AltSetting *nextAltSetting(void);

        /**
         * \brief Last AltSetting for the Interface
         *
         * This method returns a pointer to the last AltSetting
         * for the Interface.
         *
         * \see firstAltSetting(), nextAltSetting(), numAltSettings()
         */

        AltSetting *lastAltSetting(void);

    private:
        std::list<AltSetting *>::const_iterator iter;

        void setNumAltSettings(u_int8_t);
        void setParent(Device *parent);
        u_int8_t m_numAltSettings;
        Device    *m_parent;

        /* index representing the interface, in this configuration */
        int m_interfaceNumber;
        void setInterfaceNumber(int interfaceNumber);
    };

    /**
     * \brief Class representing a configuration of a Device
     *
     * The Configuration class represents a single configuration
     * of a device attached to a Universal Serial Bus.
     *
     * \author Brad Hards
     */
    class Configuration : public std::list<Interface *> {
        /**
         * Busses is a friend because it fills in the descriptor type
         * information on initialisation and rescan.
         */
        friend class Busses;
    public:
        Configuration() {};

        /**
         * \brief Configuration descriptor information output
         *
         * This method dumps out the various characteristics
         * of the configuration to standard output.
         *
         * It is mostly useful for debugging.
         */
        void dumpDescriptor(void);

        /**
         * \brief Number of Interfaces that this device has
         *
         * This is a simple accessor method that specifies the number
         * Interfaces that this device configuration has.
         */
        u_int8_t numInterfaces(void);

        /**
         * \brief First Interface for the Configuration
         *
         * This method returns a pointer to the first Interface
         * for the Configuration.
         *
         * See nextInterface() for an example of how it might be
         * used.
         *
         * \see nextInterface(), lastInterface(), numInterfaces()
         */
        Interface *firstInterface(void);

        /**
         * \brief Next Interface for the Configuration
         *
         * This method returns a pointer to the next Interface
         * for the Configuration.
         *
         * If you want to iterate through each Interface on
         * a device, you can use something like the following:
         * \code
         * USB::Configuration *this_Configuration;
         * this_Configuration = device->firstConfiguration();
         * for (i=0; i < device->numConfigurations(); i++) {
         *     this_Interface = this_Configuration->firstInterface();
         *     for (j=0; j < this_Configuration->numInterfaces(); j++) {
         *     // do something with this_Interface
         *     this_Interface = this_Configuration->nextInterface();
         *   }
         *   this_Configuration->nextConfiguration();
         * }
         * \endcode
         *
         * \see firstInterface(), lastInterface(), numInterfaces()
         */
        Interface *nextInterface(void);

        /**
         * \brief Last Interface for the Configuration
         *
         * This method returns a pointer to the last Interface
         * for the Configuration.
         *
         * \see firstInterface(), nextInterface(), numInterfaces()
         */
        Interface *lastInterface(void);

    private:
        std::list<Interface *>::const_iterator iter;

        void setDescriptor(struct usb_config_descriptor);
        /* we don't use a normal usb_config_descriptor */
        /* because that would bring in the interface list */
        u_int8_t  m_Length;
        u_int8_t  m_DescriptorType;
        u_int16_t m_TotalLength;
        u_int8_t  m_NumInterfaces;
        u_int8_t  m_ConfigurationValue;
        u_int8_t  m_Configuration;
        u_int8_t  m_Attributes;
        u_int8_t  m_MaxPower;
    };

    /**
     * \brief Class representing a Device on the Bus
     *
     * The Device class represents a single device
     * attached to a Universal Serial Bus.
     *
     * \author Brad Hards
     */
    class Device : public std::list<Configuration *> {
        /**
         * Busses is a friend because it fills in the descriptor type
         * information on initialisation and rescan.
         */
        friend class Busses;
        /**
         * Interface is a friend because it needs the handle() function to
         * perform claim(), release().
         */
        friend class Interface;
        /**
         * Endpoint is a friend because it needs the handle() function to
         * perform reads, writes, and other transactions.
         */
        friend class Endpoint;

    public:
        Device() {};
        ~Device();

        /**
         * \brief OS representation of filename for this device
         *
         * libusb++ provides a uniform way of accessing USB
         * devices irrespective of the underlying Operation System
         * representation. If you want to map the libusb++ representation
         * to the Operating System representation, you can do this
         * with filename().
         *
         * On Linux, the filename is usually something like 002, which
         * represents the second device (usually the first real device,
         * after the root hub pseudo-device) on the bus.
         *
         * \see Bus::directoryName()
         */
        std::string fileName(void);

        /**
         * \brief The vendor ID number, as provided by the device.
         *
         * This method returns a number containing the vendor
         * (manufacturer) identification number. These are allocated
         * by the USB Implementers Forum, and you can construct a
         * lookup based on the number to get the manufacturer's name,
         * even if the device does not contain a vendor string.
         *
         * \see Vendor()
         */
        u_int16_t idVendor(void);

        /**
         * \brief The product ID number, as provided by the device.
         *
         * This method returns a number containing the product
         * identification number. These are allocated
         * by the manufacturer, and should be different on each device.
         *
         * \see Product()
         */
        u_int16_t idProduct(void);

        /**
         * \brief The product's revision ID, as provided by the device.
         *
         * This method returns a number containing the product's revision.
         * This revision level is nominally binary coded decimal, but
         * hexadecimal revision levels are not uncommon. The binary coded
         * decimal version nominally has a major version in the high byte,
         * and a minor version in the low byte.
         */
        u_int16_t idRevision(void);

        /**
         * \brief The device's USB class, as provided by the device.
         *
         * This method returns a number containing the device's class.
         * These are defined by the USB Implementer's Forum.
         *
         * A code of Zero is special (and common) - it means that the
         * class is found in the Interface descriptor, rather than in the
         * Device descriptor.
         *
         * A code of 0xFF is also special (and far too common) - it means
         * that the manufacturer didn't conform to one of the defined
         * class specifications, and chose to implement a vendor specified
         * protocol.
         *
         */
        u_int8_t devClass(void);

        /**
         * \brief The device's USB subclass, as provided by the device.
         *
         * This method returns a number containing the device's subclass.
         * These subclasses are defined by the USB Implementer's Forum,
         * and only have meaning in the context of a specified class.
         */
        u_int8_t devSubClass(void);

        /**
         * \brief The device's USB protocol, as provided by the device.
         *
         * This method returns a number containing the device's protocol.
         * These protocols are defined by the USB Implementer's Forum, and
         * only have meaning in the context of a specified class and
         * subclass.
         */
        u_int8_t devProtocol(void);


        /**
         * \brief The vendor name string, as provided by the device.
         *
         * This method returns a string containing the name of the
         * device's vendor (manufacturer), as encoded into the device.
         *
         * Note that not all devices contain a vendor name, and also
         * that under some operating systems you may not be able to
         * read the vendor name without elevated privledges (typically
         * root privledges).
         *
         * \see idVendor()
         **/
        std::string Vendor(void);

        /**
         * \brief The product name string, as provided by the device.
         *
         * This method returns a string containing the name of the
         * device's product name, as encoded into the device.
         *
         * Note that not all devices contain a product name, and also
         * that under some operating systems you may not be able to
         * read the vendor name without elevated privledges (typically
         * root privledges).
         *
         * \see idProduct()
         **/
        std::string Product(void);

        /**
         * \brief The serial number string, as provided by the device.
         *
         * This method returns a string containing a serial number for
         * the device, as encoded into the device.
         *
         * Note that few devices contain a serial number string, and also
         * that under some operating systems you may not be able to
         * read the serial number without elevated privledges (typically
         * root privledges). The USB specification requires that serial
         * numbers are unique if they are provided, but adherence to this
         * requirement by manufacturers is not universal.
         **/
        std::string SerialNumber(void);

        /**
         * \brief Number of Configurations that this device has
         *
         * This is a simple accessor method that specifies the number
         * configurations that this device has.
         */
        u_int8_t numConfigurations(void);

        /**
         * \brief fetch an arbitrary string from the device
         *
         * \param string the string from the device. You can typically
         * pass in an empty string for this.
         * \param index the index of the string required
         * \param lang the language ID to use. Defaults to using the
         * first language ID.
         *
         * \return length of string, or 0 on error.
         */
        int string(std::string &buf, int index, u_int16_t lang=0);

        /**
         * \brief First Configuration for the Device
         *
         * This method returns a pointer to the first Configuration
         * for the Device.
         *
         * See nextConfiguration() for an example of how it might be
         * used.
         */
        Configuration *firstConfiguration(void);

        /**
         * \brief Next Configuration for the Device
         *
         * This method returns a pointer to the next Configuration
         * for the Device.
         *
         * If you want to iterate through each Configuration on
         * a device, you can use something like the following:
         * \code
         * USB::Configuration *this_Configuration;
         * this_Configuration = device->firstConfiguration();
         * for (i=0; i < device->numConfigurations(); i++) {
         *   // do something with this_Configuration
         *   this_Configuration->nextConfiguration();
         * }
         * \endcode
         */
        Configuration *nextConfiguration(void);

        /**
         * \brief Last Configuration for the Device
         *
         * This method returns a pointer to the last Configuration
         * for the Device.
         *
         */
        Configuration *lastConfiguration(void);

        /**
         * \brief USB control transfer
         *
         * This method performs a standard control transfer to the default
         * endpoint. See the USB specification for more details on this.
         *
         * \param requestType corresponds to the bmRequestType field
         * in the transfer
         * \param request corresponds to the bRequest field in the
         * transfer
         * \param value corresponds to the wValue field in the transfer
         * \param index corresponds to the wIndex field in the transfer
         * \param length corresponds to the wLength field in the transfer
         * \param payload corresponds to the data phase of a control
         * transfer
         * \param timeout is the timeout period for the control transfer,
         * in milliseconds
         *
         * \return number of bytes sent or received, or a negative number
         * in case of error.
         */
        int controlTransfer(u_int8_t requestType, u_int8_t request,
                    u_int16_t value, u_int16_t index, u_int16_t length,
                    unsigned char *payload,
                    int timeout = 100);

#ifdef USE_UNTESTED_LIBUSBPP_METHODS
        /**
         * \brief USB device reset
         *
         * This method performs a device reset - see USB Specification
         * 9.1 for how this changes the device state to the Default state.
         *
         * \return 0 on success, or a negative number in case of error.
         */
        int reset(void);

        /**
         * \brief Set device configuration
         *
         * This method sets the device to a particular Configuration.
         *
         * \param configurationNumber the configuration that the device
         * should be changed to.
         *
         * \return 0 on success, or a negative number in case of error.
         */
        int setConfiguration(int configurationNumber);
#endif /* USE_UNTESTED_LIBUSBPP_METHODS */

    private:
        std::list<Configuration *>::const_iterator iter;

        struct usb_dev_handle *handle();
        void setFileName(std::string);
        void setDescriptor(struct usb_device_descriptor);
        void setVendor(std::string);
        void setProduct(std::string);
        void setSerialNumber(std::string);
        void setDevHandle(struct usb_dev_handle *);
        std::string m_fileName;
        std::string m_Vendor;
        std::string m_Product;
        std::string m_SerialNumber;
        struct usb_device *m_dev;
        struct usb_dev_handle *m_handle;
        struct usb_device_descriptor m_descriptor;
    };

    /**
     * \brief Class representing a single bus on the machine
     *
     * This class is essentially a list of Device class instances
     */
    class Bus : public std::list<Device *> {
        /**
         * Busses is a friend because it fills in the directory name
         * information on initialisation and rescan.
         */
        friend class Busses;
    public:
        Bus() {};
        /**
         * \brief OS representation of directory name for this Bus
         *
         * libusb++ provides a uniform way of accessing USB
         * busses irrespective of the underlying Operation System
         * representation. If you want to map the libusb++ representation
         * to the Operating System representation, you can do this
         * with directory name().
         *
         * On Linux, the directoryname is usually something like 003, which
         * represents the third bus on the host.
         *
         * \see Directory::filename()
         */
        std::string directoryName(void);
    private:
        std::list<Device *>::const_iterator iter;

        void setDirectoryName(std::string);
        std::string m_directoryName;
    };

    /**
     * \brief A vendor/product ID pair
     *
     * DeviceID provides a list of (vendor, product) identification
     * pairs. It is intended for use in a list of device numbers to
     * search for, but there is no reason why it couldn't be used for a
     * general purpose (vendor,product) tuple if you had some reason for
     * this.
     *
     * The description for Busses::match() provides an example of how
     * this class might be used.
     *
     * \see DeviceIDList, Busses::match()
     */
    class DeviceID {
    public:
        DeviceID() {};
        /**
         * \brief Standard constructor
         *
         * This constructor takes (vendor, product) tuple, which are
         * stored away.
         *
         * \param vendor the 16 bit vendor number for the device
         * \param product the 16 bit product number for the device
         */
        DeviceID(u_int16_t vendor, u_int16_t product);

        /**
         * \brief vendor number for the device
         *
         * This method returns the 16 bit vendor number.
         */
        u_int16_t vendor(void);

        /**
         * \brief product number for the device
         *
         * This method returns the 16 bit product number.
         */
        u_int16_t product(void);

    private:
        u_int16_t m_vendor;
        u_int16_t m_product;
    };

    /**
     * \brief A list of vendor/product pairs
     *
     * DeviceIDList provides a list of DeviceID classes, which is
     * essentially a list of (vendor, product) identification pairs.
     *
     * \see DeviceID
     */
    typedef std::list<DeviceID> DeviceIDList;

    /**
     * \brief Class representing all the busses on the machine
     *
     * This class is essentially a list of Bus class instances
     */
    class Busses : public std::list<Bus *> {
    public:
        Busses();

        /**
         * \brief Update method
         *
         * This method can be called to rescan the various devices
         * attached to the various busses. You should use it to
         * update if things change. Unfortunately there is no
         * way to automatically detect this change in a portable way,
         * so worst case is that you need to call this using some
         * kind of timer in the background.
         */
        void rescan(void);

        /**
         * \brief find all devices with matching device class designator
         *
         * This method searches every device on every bus, and returns a
         * list of pointers to the devices that have a matching device
         * class code
         */
        std::list<Device *> match(u_int8_t Class);

        /**
         * \brief find all devices with matching device IDs
         *
         * This method searches every device on every bus, and returns a
         * list of pointers to the devices that have a matching device
         * ID. That is, if the (vendor, product) tuple of a device matches
         * one of the tuples on the list, then the device will be added to
         * the list of matches.
         *
         * An example of usage is shown below:
         * \code
         * USB::Busses buslist;
         * USB::Device *device;
         * std::list<USB::Device> miceFound;
         * USB::DeviceIDList mouseList;
         *
         * mouseList.append(USB::DeviceID(VENDOR_LOGITECH, 0xC00E)); // Wheel Mouse Optical
         * mouseList.append(USB::DeviceID(VENDOR_LOGITECH, 0xC012)); // MouseMan Dual Optical
         * mouseList.append(USB::DeviceID(VENDOR_LOGITECH, 0xC506)); // MX700 Optical Mouse
         *
         * miceFound = buslist.match(mouseList);
         *
         * for ( device = miceFound.first(); device; device = miceFound.next() ) {
         *     // do something with each mouse that matched
         * }
         * FIXME: This is incorrect now
         * \endcode
         */
        std::list<Device *> match(DeviceIDList);

    private:
        std::list<Bus *>::const_iterator iter;
    };

    class Error {
    public:
    private:
    };

}
#endif /* __USBPP_HEADER__ */